home *** CD-ROM | disk | FTP | other *** search
/ Power Programmierung / Power-Programmierung (Tewi)(1994).iso / magazine / msysjour / vol03 / 05 / filter / ext.doc next >
Text File  |  1988-02-01  |  16KB  |  463 lines
  1. /*
  2. EXT.DOC
  3.  
  4. This file documents each of the low-level editing functions that can be
  5. called from a Microsoft-Editor C extension.
  6.  
  7. The types COL and LINE, formally declared in the file EXT.H, are short and
  8. long integers, respectively.  A variable of type COL refers to a column
  9. in a file, and a variable of type LINE refers to a line (in other words, a
  10. row) in a file.  Numbering for both COL and LINE variables begins with
  11. 0.  Therefore, line 0 is the first line in the file.
  12. */
  13.  
  14.  
  15. /*  Replace - edits a character in a file
  16.  *
  17.  *  The Replace function inserts character c at position (x, y) in the file
  18.  *  pFile.  If fInsert equals TRUE (-1) the function moves remaining characters
  19.  *  on the line over by one space.  If fInsert equals FALSE (0) function re-
  20.  *  laces the character at specified position.  The function takes no action if
  21.  *  fInsert equals FALSE, and c is identical to the character at specified
  22.  *  position.
  23.  *
  24.  *  c        Character to place into the file
  25.  *  x, y    Column and row (respectively) of position of insertion
  26.  *  pFile    Handle to file being modified
  27.  *  fInsert    If TRUE (-1), inserts before character at specified position;
  28.  *              otherwise, overwrites character at specified position
  29.  *
  30.  *  returns    TRUE if line is successfully edited, FALSE if line is too
  31.  *        long
  32.  */
  33. flagType pascal Replace (c, x, y, pFile, fInsert)
  34. char c;
  35. COL  x;
  36. LINE y;
  37. PFILE pFile;
  38. flagType fInsert;
  39.  
  40.  
  41. /*  MoveCur - moves the cursor to a specified location in the current file
  42.  *
  43.  *  The MoveCur function moves the cursor to specified position within the
  44.  *  current file.  If the cursor is within the same window, then no window
  45.  *  movement occurs.  Otherwise, the cursor is placed at a common position
  46.  *  specified by the numeric switch "hike."
  47.  *
  48.  *  x        Column where cursor is to appear in file
  49.  *  y        Line (row) where cursor is to appear in file
  50.  */
  51. void pascal MoveCur (x, y)
  52. COL  x;
  53. LINE y;
  54.  
  55.  
  56. /*  DelLine - deletes lines from a file
  57.  *
  58.  *  The DelLine function deletes lines yStart through yEnd, inclusive, in
  59.  *  the file pFile.
  60.  *
  61.  *  pfile    Handle to file from which lines are to be deleted
  62.  *  yStart    First line to be deleted
  63.  *  yEnd    Last line to be deleted
  64.  */
  65. void pascal DelLine (pfile, yStart, yEnd)
  66. PFILE pfile;
  67. LINE yStart, yEnd;
  68.  
  69.  
  70. /*  DelBox - deletes a rectangular area (box) from a file
  71.  *
  72.  *  The DelBox function deletes all spaces in the box delimited
  73.  *  by the positions (xLeft, yTop) and (xRight, yBottom).  The
  74.  *  box includes both corners specified in the function call.
  75.  *
  76.  *  pFile        Handle to file to be modified
  77.  *  xLeft, yTop     Column and line of start of box
  78.  *  xRight, yBottom     Column and line of end of box
  79.  */
  80. void pascal DelBox (pFile, xLeft, yTop, xRight, yBottom)
  81. PFILE pFile;
  82. COL  xLeft, xRight;
  83. LINE yTop, yBottom;
  84.  
  85.  
  86. /*  DelStream - deletes a stream of text from a file
  87.  *
  88.  *  The DelStream function deletes the stream of text beginning with
  89.  *  position (xStart, yStart), up to but not including position
  90.  *  (xEnd, yEnd), within file pFile.
  91.  *
  92.  *  pFile        Handle to file to be modified
  93.  *  xStart, yStart     Column and line of start of stream
  94.  *  xEnd, yEnd        Column and line of end of stream
  95.  */
  96. void pascal DelStream (pFile, xStart, yStart, xEnd, yEnd)
  97. PFILE pFile;
  98. COL  xStart, xEnd;
  99. LINE yStart, yEnd;
  100.  
  101.  
  102. /*  GetLine - retrieves a line of text
  103.  *
  104.  *  The GetLine function retrieves a line of text from the specified
  105.  *  file and places the text in the specified buffer.  The text has
  106.  *  all tabs expanded into spaces, and no carriage-return or line-feed
  107.  *  character is included.  Lines requested beyond the end of the file
  108.  *  are considered empty.
  109.  *
  110.  *  line    Number of the line to be retrieved
  111.  *  buf     Buffer for text of the line
  112.  *  pfile    Handle of file from which the line is to be retrieved
  113.  *
  114.  *  returns     The number of characters retrieved
  115.  */
  116. int pascal GetLine (line, buf, pfile)
  117. LINE line;
  118. char far *buf;
  119. PFILE pfile;
  120.  
  121.  
  122. /*  AddFile - creates a file buffer
  123.  *
  124.  *  The AddFile function creates and initializes a file buffer.  The
  125.  *  contents are initially empty.  A new file is not placed on disk
  126.  *  until the FileWrite function is called. 
  127.  *
  128.  *  p        Character pointer to name
  129.  *
  130.  *  returns    Handle to internal file structure
  131.  */
  132. PFILE pascal AddFile (p)
  133. char far *p;
  134.  
  135.  
  136. /*  DelFile - deletes contents of file
  137.  *
  138.  *  The DelFile function deletes the entire contents of an internal
  139.  *  file buffer.  The effect of deleting contents can be made
  140.  *  permanent by calling the FileWrite function, which replaces the
  141.  *  contents of the file on disk with the contents of the internal
  142.  *  file buffer.
  143.  *
  144.  *  pFile    Handle to file that is to be cleared
  145.  */
  146. void pascal DelFile (pFile)
  147. PFILE pFile;
  148.  
  149.  
  150. /*  FileNameToHandle - returns handle corresponding to the file name
  151.  *
  152.  *  The FileNameToHandle function searches for the specified file
  153.  *  and returns a handle to the file if found.  If pName points to a
  154.  *  zero-length string, then the function returns a handle to the current
  155.  *  file.  Otherwise, the function searches for the file named by pName,
  156.  *  which may include a complete path.  If pName not found and pShortName
  157.  *  is not a NULL pointer, then the function scans the information file
  158.  *  for a file name that matches pShortName.  If a match is found, then
  159.  *  the function uses the complete path name in the information file.
  160.  *
  161.  *  pName    Pointer to name of file
  162.  *  pShortName    Pointer to short name of file (this parameter may be NULL)
  163.  *
  164.  *  Returns    Handle to specified file (if found) or NULL.
  165.  */
  166. PFILE pascal FileNameToHandle (pName, pShortName)
  167. char far *pName, *pShortName;
  168.  
  169.  
  170. /*  RemoveFile - frees up all resources attached to a particular file
  171.  *
  172.  *  The RemoveFile function removes a file handle from memory, along
  173.  *  with the file buffer and all other memory-resident information about the
  174.  *  file.  Calling this function helps to free up main memory, but it has
  175.  *  no effect on the file as stored on disk.
  176.  *
  177.  *  pFileRem    File handle to be removed
  178.  */
  179. flagType pascal RemoveFile (pFileRem)
  180. PFILE     pFileRem;
  181.  
  182.  
  183. /*  CopyLine - copies lines from one file to another
  184.  *
  185.  *  The CopyLine function copies lines yStart through yEnd, inclusive,
  186.  *  and inserts them into the destination file just before line yDst.  If
  187.  *  the handle to the source file is NULL, then the function inserts a
  188.  *  blank line into the destination file (in that case, yStart and yEnd
  189.  *  are ignored).
  190.  *
  191.  *  pFileSrc    Handle to source file
  192.  *  pFileDst    Handle to destination file
  193.  *  yStart    First line to be copied
  194.  *  yEnd    Last line to be copied
  195.  *  yDst    Destination of copy
  196.  */
  197. void pascal CopyLine (pFileSrc, pFileDst, yStart, yEnd, yDst)
  198. PFILE pFileSrc, pFileDst;
  199. LINE yStart, yEnd, yDst;
  200.  
  201.  
  202. /*  CopyBox - copies a rectangular area (box) from one file to another
  203.  *
  204.  *  The CopyBox function copies the box delimited by positions (xLeft, yTop)
  205.  *  and (xRight, yBottom) in the source file and inserts this box just
  206.  *  before position (xDst, yDst) in the destination file.  If the the
  207.  *  source-file handle is NULL, a blank space is inserted.
  208.  *
  209.  *  The box in the source file includes both corners specified in the
  210.  *  function call.
  211.  *
  212.  *  pFileSrc        Handle to source file
  213.  *  pFileDst        Handle to destination file
  214.  *  xLeft, yTop     Column and line of beginning of copy
  215.  *  xRight, yBottom      Column and line of end of copy
  216.  *  xDst, yDst        Column and line of destination of copy
  217.  */
  218. void pascal CopyBox (pFileSrc, pFileDst, xLeft, yTop, xRight, yBottom, xDst, yDst)
  219. PFILE pFileSrc, pFileDst;
  220. COL  xLeft, xRight, xDst;
  221. LINE yTop, yBottom, yDst;
  222.  
  223.  
  224. /*  CopyStream - copies a stream of text
  225.  *
  226.  *  The CopyStream function copies the stream of text (including newlines)
  227.  *  beginning at position (xStart, yStart), up to but not including position
  228.  *  (xEnd, yEnd).  The stream of text is inserted into the destination file
  229.  *  just before position (xDst, yDst).  If the source-file handle is NULL,
  230.  *  a blank space is inserted.
  231.  *
  232.  *  pFileSrc        Source file handle
  233.  *  pFileDst        Destination file handle
  234.  *  xStart, yStart     Column and line of beginning of copy
  235.  *  xEnd, yEnd        Column and line of end of copy
  236.  *  xDst, yDst        Column and line of destination of copy
  237.  */
  238. void pascal CopyStream (pFileSrc, pFileDst, xStart, yStart, xEnd, yEnd, xDst, yDst)
  239. PFILE pFileSrc, pFileDst;
  240. COL  xStart, xEnd, xDst;
  241. LINE yStart, yEnd, yDst;
  242.  
  243.  
  244. /*  pFileToTop - makes the specified file visible in the current window
  245.  *
  246.  *  In effect, the pFileToTop function selects a file as the current
  247.  *  file and makes it visible in the current window.  The function 
  248.  *  accomplishes this operation by moving the specified file handle to
  249.  *  the top of the "stack" of file handles attached to the current
  250.  *  window.
  251.  *
  252.  *  pFileTmp    Handle of file to bring to top of stack
  253.  */
  254. void pascal pFileToTop (pFileTmp)
  255. PFILE pFileTmp;
  256.  
  257.  
  258. /*  Display - updates the physical display
  259.  *
  260.  *  The Display function refreshes the screen, by examining editing
  261.  *  changes and making the minimum screen changes necessary.  A keystroke
  262.  *  interrupts the function and causes immediate return.
  263.  *
  264.  *  You do not normally need to use the Display function to see the
  265.  *  results of an edit on the screen.  The function is typically useful
  266.  *  when you have an SWI_SPECIAL function that alters a file directly.
  267.  */
  268. void pascal Display ()
  269.  
  270.  
  271. /*  FileRead - reads the contents of a file into the file buffer
  272.  *
  273.  *  The FileRead function reads the contents of the specified disk file
  274.  *  and stores them in the internal file buffer specified by pFile.  The
  275.  *  old contents of the file buffer are lost.
  276.  *
  277.  *  name    Pointer to name of file to be read
  278.  *  pFile    Handle to internal file to receive contents
  279.  *
  280.  *  returns     TRUE (-1) if successful; FALSE (0) if file could not be read
  281.  */
  282. flagType pascal FileRead (name, pFile)
  283. char far *name;
  284. PFILE pFile;
  285.  
  286.  
  287. /*  FileWrite - writes buffer contents out to disk
  288.  *
  289.  *  The FileWrite function writes the contents of the specified file buffer
  290.  *  out to the disk file specified by savename.  If savename is a NULL pointer,
  291.  *  then the function writes the file buffer out to the disk file with the
  292.  *  same name.  The FileWrite function first writes contents to a temporary
  293.  *  file; if the write operation is successful, then the temporary file is
  294.  *  renamed to the destination file.
  295.  *
  296.  *  savename    Pointer to name of file to be overwritten
  297.  *  pFile    Handle to file buffer to write
  298.  */
  299. flagType pascal FileWrite (savename, pFile)
  300. char far *savename;
  301. PFILE pFile;
  302.  
  303.  
  304. /*  SetKey - associates an editor function with a keystroke
  305.  *
  306.  *  The SetKey function creates a function assignment.  Any current assignment
  307.  *  to the keystroke is discarded and each time that particular keystroke is
  308.  *  received, the corresponding editor function will be invoked.
  309.  *
  310.  *  pFunction    Pointer to name of string being assigned
  311.  *  pKey    Pointer to keystroke
  312.  *
  313.  *  returns     TRUE (-1) if a successful assignment was made; FALSE (0)
  314.  *              otherwise
  315.  */
  316. flagType pascal SetKey (pFunction, pKey)
  317. char far *pFunction, *pKey;
  318.  
  319.  
  320. /*  DoMessage - outputs a string on the dialog line
  321.  * 
  322.  *  The DoMessage function prints the specified string on the dialog
  323.  *  line.
  324.  *
  325.  *  pStr    Pointer to character string to print
  326.  *
  327.  *  returns    Number of characters written
  328.  *
  329.  */
  330. int pascal DoMessage (pStr)
  331. char far * pStr;
  332.  
  333.  
  334.  
  335. /*  PutLine - places a line of text into a file
  336.  *
  337.  *  The PutLine function places the indicated buffer string into
  338.  *  the specified file, replacing an existing line.  If the specified
  339.  *  line is out of range, then the PutLine function enlarges the
  340.  *  file, and inserts as many blank lines as needed at the end of the
  341.  *  file.  The buffer line should have no carriage return or line feed;
  342.  *  the PutLine function adds a newline automatically.
  343.  *
  344.  *  line    Number of line to be replaced
  345.  *  buf     Buffer with line of text to be placed in file
  346.  *  pfile    Handle to file
  347.  */
  348. void pascal PutLine (line, buf, pfile)
  349. LINE line;
  350. char far *buf;
  351. PFILE pfile;
  352.  
  353.  
  354. /*  BadArg - displays a message that a bad argument has been received
  355.  *
  356.  *  The "bad argument" message is printed on the dialog line.
  357.  */
  358. flagType pascal BadArg (void);
  359.  
  360.  
  361.  
  362. /*  FileLength - returns the number of lines in the file
  363.  *
  364.  *  The FileLength function is particularly useful for global operations,
  365.  *  in which it is necessary to know where the end of the file is.
  366.  *
  367.  *  pFile    Handle to file
  368.  *
  369.  *  returns    Number of lines in file
  370.  */
  371. LINE pascal FileLength (pFile)
  372. PFILE pFile;
  373.  
  374.  
  375. /*  GetCursor - returns the current cursor position
  376.  *
  377.  *  The GetCursor function indicates current cursor position by
  378.  *  modifying the integers that px and py point to.  The function
  379.  *  sets *px to the current cursor column, and *py to the current
  380.  *  cursor line.
  381.  *
  382.  *  px        Pointer to column-position variable
  383.  *  py        Pointer to line-position variable
  384.  */
  385. void pascal GetCursor (px, py);
  386. COL  far *px;
  387. LINE far *py;
  388.  
  389.  
  390. /*  fExecute - executes a Microsoft-Editor macro
  391.  *
  392.  *  The fExecute function executes a macro, using the standard rules
  393.  *  for macro execution (see the Microsoft Editor User's Guide for details).
  394.  *
  395.  *  pStr    Pointer to macro string to execute
  396.  *
  397.  *  returns    Return value of last executed macro
  398.  */
  399. flagType pascal fExecute (pStr)
  400. char far *pStr;
  401.  
  402.  
  403. /*  ReadCmd  - returns next command from user
  404.  *
  405.  *  The ReadCmd waits for input from user.  The next keystroke is
  406.  *  translated into a function that is not executed.  Instead, the
  407.  *  editor passes information about the function in the form of a
  408.  *  structure of type cmdDesc.  This structure is declared in the file
  409.  *  EXT.H and is described in Chapter 8 of the Microsoft Editor    
  410.  *  User's Guide.  Once intercepted, the keystroke cannot be placed
  411.  *  back for execution.
  412.  *
  413.  *  returns    Pointer to cmdDesc structure corresponding to next keystroke
  414.  */
  415. PCMD pascal ReadCmd ();
  416.  
  417.  
  418. /*  ReadChar - returns next raw keystroke
  419.  *
  420.  *  The ReadChar intercepts the next keystroke from the user.  No action
  421.  *  is taken, but information about the keystroke is passed.  Once
  422.  *  intercepted, the keystroke cannot be placed back for execution.
  423.  *
  424.  *  returns    a long value containing information on the keystroke:
  425.  *
  426.  *        byte 0: ASCII code for character
  427.  *        byte 1: scan code for character
  428.  *        byte 2: shift info for character:
  429.  *                (S)HIFT, (C)TRL, (A)LT, (N)UMLOCK
  430.  *                Format is: SxCAxNxx
  431.  *        byte 3: 0
  432.  *
  433.  *  In the format for byte 2, each "x" indicates an unusued bit. The
  434.  *  bits S, C, A, and N are each on or off, depending on the associated
  435.  *  condition.  For example, if the SHIFT, CTRL, and ALT conditions are
  436.  *  all on, but not the NUMLOCK condition, then byte 2 will be returned as
  437.  *  10110000.  Note: the "N" bit is always 0, unless the the key pressed
  438.  *  is on the numeric keypad.
  439.  */
  440. long pascal ReadChar();
  441.  
  442.  
  443. /*  KbUnHook - Disable Microsoft Editor's logical keyboard
  444.  *
  445.  *  The KbUnHook function changes the "focus" of the keyboard so that
  446.  *  keyboard input is no longer read by the editor.  When attempting to
  447.  *  use system-level calls to read from the keyboard, it is necessary to
  448.  *  first call this function.
  449.  *
  450.  *  In paticular, it is necessary to call the KbUnHook function before
  451.  *  transferring control to a program that reads from the keyboard.
  452.  */
  453. void pascal KbUnHook();
  454.  
  455.  
  456. /*  KbHook - Enable Microsoft Editor's logical keyboard
  457.  *
  458.  *  The KbHook function reverses the affect of the KbUnHook function
  459.  *  (described above), and restores normal keyboard-input reading
  460.  *  by the editor.
  461.  */
  462. void pascal KbHook();
  463.